<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat Configuration Reference - The Manager Component</title><meta content="Craig R. McClanahan" name="author"><meta content="Yoav Shapira" name="author"><style media="print" type="text/css">
			.noPrint {display: none;}
			td#mainBody {width: 100%;}
		</style></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img border="0" alt="
    The Apache Tomcat Servlet/JSP Container
  " align="right" src="../../images/tomcat.gif"></a></td><td><h1><font face="arial,helvetica,sanserif">The Apache Tomcat 5.5 Servlet/JSP Container</font></h1></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img border="0" alt="Apache Logo" align="right" src="../../images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade="noshade"></td></tr><tr><!--RIGHT SIDE MAIN BODY--><td id="mainBody" align="left" valign="top" width="80%"><h1>Apache Tomcat Configuration Reference</h1><h2>The Manager Component</h2><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#Common_Attributes">Common Attributes</a></li><li><a href="#Standard_Implementation">Standard Implementation</a></li></ol></li><li><a href="#Nested_Components">Nested Components</a></li><li><a href="#Special_Features">Special Features</a><ol><li><a href="#Restart_Persistence">Restart Persistence</a></li></ol></li></ul>
</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>

  <p>The <strong>Manager</strong> element represents the <em>session
  manager</em> that will be used to create and maintain HTTP sessions
  as requested by the associated web application.</p>

  <p>A Manager element MAY be nested inside a
  <a href="context.html">Context</a> component.  If it is not included,
  a default Manager configuration will be created automatically, which
  is sufficient for most requirements.</p>

</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>

  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Common Attributes"><!--()--></a><a name="Common_Attributes"><strong>Common Attributes</strong></a></font></td></tr><tr><td><blockquote>

    <p>All implementations of <strong>Manager</strong>
    support the following attributes:</p>

    <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><code>className</code></td><td valign="center" align="left">
        <p>Java class name of the implementation to use.  This class must
        implement the <code>org.apache.catalina.Manager</code> interface.
        If not specified, the standard value (defined below) will be used.</p>
      </td></tr><tr><td valign="center" align="left"><code>distributable</code></td><td valign="center" align="left">
        <p>Set to <code>true</code> to ask the session manager to enforce
        the restrictions described in the Servlet Specification on
        distributable applications (primarily, this would mean that all
        session attributes must implement <code>java.io.Serializable</code>).
        Set to <code>false</code> (the default) to not enforce these
        restrictions.</p>

        <p><strong>NOTE</strong> - The value for this property is inherited
        automatically based on the presence or absence of the
        <code>&lt;distributable&gt;</code> element in the web application
        deployment descriptor (<code>/WEB-INF/web.xml</code>).</p>
      </td></tr></table>

  </blockquote></td></tr></table>


  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Standard Implementation"><!--()--></a><a name="Standard_Implementation"><strong>Standard Implementation</strong></a></font></td></tr><tr><td><blockquote>

    <p>Tomcat provides two standard implementations of <strong>Manager</strong>
    for use - the default one stores active sessions, while the optional one
    stores active sessions that have been swapped out (in addition to saving
    sessions across a restart of Tomcat) in a storage location that is selected
    via the use of an appropriate <strong>Store</strong> nested element.</p>

    <h3>Standard Manager Implementation</h3>

    <p>The standard implementation of <strong>Manager</strong> is
    <strong>org.apache.catalina.session.StandardManager</strong>.
    It supports the following additional attributes (in addition to the
    common attributes listed above):</p>

    <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><code>algorithm</code></td><td valign="center" align="left">
        <p>Name of the <em>Message Digest</em> algorithm used to calculate
        session identifiers produced by this Manager.  This value must
        be supported by the <code>java.security.MessageDigest</code> class.
        If not specified, the default value is "MD5".</p>
      </td></tr><tr><td valign="center" align="left"><code>entropy</code></td><td valign="center" align="left">
        <p>A String value that is utilized when seeding the random number
        generator used to create session identifiers for this Manager.
        If not specified, a semi-useful value is calculated, but a long
        String value should be specified in security-conscious
        environments.</p>
      </td></tr><tr><td valign="center" align="left"><code>maxActiveSessions</code></td><td valign="center" align="left">
        <p>The maximum number of active sessions that will be created by
        this Manager, or -1 (the default) for no limit.</p>
      </td></tr><tr><td valign="center" align="left"><code>maxInactiveInterval</code></td><td valign="center" align="left">
        <p>The initial maximum time interval, in seconds, 
        between client requests before a session is invalidated. A negative value
        will result in sessions never timing out. If the attribute is not provided,
        a default of 60 seconds is used.</p>
        
        <p>This attribute provides the initial value whenever a 
        new session is created, but the interval may be dynamically 
        varied by a servlet via the 
        <code>setMaxInactiveInterval</code> method of the <code>HttpSession</code> object.</p>
      </td></tr><tr><td valign="center" align="left"><code>pathname</code></td><td valign="center" align="left">
        <p>Absolute or relative (to the work directory for this Context)
        pathname of the file in which session state will be preserved
        across application restarts, if possible.  The default is
        "SESSIONS.ser".  See <a href="#Restart Persistence">Restart
        Persistence</a> for more information. Restart persistence may be 
        disabled by setting this attribute to an empty string.</p>
      </td></tr><tr><td valign="center" align="left"><code>processExpiresFrequency</code></td><td valign="center" align="left">
        <p>Frequency of the session expiration, and related manager operations.
        Manager operations will be done once for the specified amount of
        backgrondProcess calls (i.e., the lower the amount, the more often the
        checks will occur). The minimum value is 1, and the default value is 6.
        </p>
      </td></tr><tr><td valign="center" align="left"><code>randomClass</code></td><td valign="center" align="left">
        <p>Java class name of the <code>java.util.Random</code>
        implementation class to use.  If not specified, the default value is
        <code>java.security.SecureRandom</code>.</p>
      </td></tr><tr><td valign="center" align="left"><code>sessionIdLength</code></td><td valign="center" align="left">
       <p>The length of session ids created by this Manager, excluding any
        JVM route information used for load balancing. 
        The default is 16.</p>
      </td></tr></table>

    <h3>Persistent Manager Implementation</h3>

    <p><em><strong>WARNING - Use of this Manager implementation
    has not been thoroughly tested, and should be considered experimental!
    </strong></em></p>
    
    <p><strong>NOTE:</strong> You must set the
    <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
    <a href="systemprops.html">system property</a> to <code>true</code> for
    the persistent manager to work correctly.</p>
    
    <p>The persistent implementation of <strong>Manager</strong> is
    <strong>org.apache.catalina.session.PersistentManager</strong>.  In
    addition to the usual operations of creating and deleting sessions, a
    <code>PersistentManager</code> has the capability to swap active (but
    idle) sessions out to a persistent storage mechanism, as well as to save
    all sessions across a normal restart of Tomcat.  The actual persistent
    storage mechanism used is selected by your choice of a
    <strong>Store</strong> element nested inside the <strong>Manager</strong>
    element - this is required for use of <code>PersistentManager</code>.</p>

    <p>This implementation of Manager supports the following attributes in
    addition to the <a href="#Common Attributes">Common Attributes</a>
    described earlier.</p>

    <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><code>algorithm</code></td><td valign="center" align="left">
        <p>Name of the <em>Message Digest</em> algorithm used to calculate
        session identifiers produced by this Manager.  This value must
        be supported by the <code>java.security.MessageDigest</code> class.
        If not specified, the default value is "MD5".</p>
      </td></tr><tr><td valign="center" align="left"><code>className</code></td><td valign="center" align="left">
        <p>Java class name of the implementation to use.  This class must
        implement the <code>org.apache.catalina.Manager</code> interface.
        You <strong>must</strong> specify
        <code>org.apache.catalina.session.PersistentManager</code> to use
        this manager implementation.</p>
      </td></tr><tr><td valign="center" align="left"><code>entropy</code></td><td valign="center" align="left">
        <p>A String value that is utilized when seeding the random number
        generator used to create session identifiers for this Manager.
        If not specified, a semi-useful value is calculated, but a long
        String value should be specified in security-conscious
        environments.</p>
      </td></tr><tr><td valign="center" align="left"><code>maxActiveSessions</code></td><td valign="center" align="left">
        <p>The maximum number of active sessions that will be created by
        this Manager, or -1 (the default) for no limit.</p>
      </td></tr><tr><td valign="center" align="left"><code>maxIdleBackup</code></td><td valign="center" align="left">
        <p>The time interval (in seconds) since the last access to a session
        before it is eligible for being persisted to the session store, or
        <code>-1</code> to disable this feature.  By default, this feature is
        disabled.</p>
      </td></tr><tr><td valign="center" align="left"><code>maxIdleSwap</code></td><td valign="center" align="left">
        <p>The time interval (in seconds) since the last access to a session
        before it should be persisted to the session store, and
        passivated out of the server's memory, or <code>-1</code> to disable
        this feature.  If this feature is enabled, the time interval specified
        here should be equal to or longer than the value specified for
        <code>maxIdleBackup</code>.  By default, this feature is disabled.</p>
      </td></tr><tr><td valign="center" align="left"><code>minIdleSwap</code></td><td valign="center" align="left">
        <p>The time interval (in seconds) since the last access to a session
        before it will be eligible to be persisted to the session store, and
        passivated out of the server's memory, or <code>-1</code> for this
        swapping to be available at any time.  If specified, this value should
        be less than that specified by <code>maxIdleSwap</code>.  By default,
        this value is set to <code>-1</code>.</p>
      </td></tr><tr><td valign="center" align="left"><code>maxInactiveInterval</code></td><td valign="center" align="left">
        <p>The initial maximum time interval, in seconds, 
        between client requests before a session is invalidated. A negative value
        will result in sessions never timing out. If the attribute is not provided,
        a default of 60 seconds is used.</p>
        
        <p>This attribute provides the initial value whenever a 
        new session is created, but the interval may be dynamically 
        varied by a servlet via the 
        <code>setMaxInactiveInterval</code>method of the <code>HttpSession</code> object.</p>
      </td></tr><tr><td valign="center" align="left"><code>randomClass</code></td><td valign="center" align="left">
        <p>Java class name of the <code>java.util.Random</code>
        implementation class to use.  If not specified, the default value is
        <code>java.security.SecureRandom</code>.</p>
      </td></tr><tr><td valign="center" align="left"><code>saveOnRestart</code></td><td valign="center" align="left">
        <p>Should all sessions be persisted and reloaded when Tomcat is shut
        down and restarted (or when this application is reloaded)?  By default,
        this attribute is set to <code>true</code>.</p>
      </td></tr><tr><td valign="center" align="left"><code>sessionIdLength</code></td><td valign="center" align="left">
        <p>The length of session ids created by this Manager, excluding any
        JVM route information used for load balancing. 
        The default is 16.</p>
      </td></tr></table>

    <p>In order to successfully use a PersistentManager, you must nest inside
    it a <strong>&lt;Store&gt;</strong> element, as described below.</p>

  </blockquote></td></tr></table>


</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Nested Components"><!--()--></a><a name="Nested_Components"><strong>Nested Components</strong></a></font></td></tr><tr><td><blockquote>

  <h3>Standard Manager Implementation</h3>

  <p>If you are using the <em>Standard Manager Implementation</em>
  as described above, no elements may be nested inside your
  <strong>&lt;Manager&gt;</strong> element.</p>

  <h3>Persistent Manager Implementation</h3>

  <p>If you are using the <em>Persistent Manager Implementation</em>
  as described above, you <strong>MUST</strong> nest a
  <strong>&lt;Store&gt;</strong> element inside, which defines the
  characteristics of the persistent data storage.  Two implementations
  of the <code>&lt;Store&gt;</code> element are currently available,
  with different characteristics, as described below.</p>

  <h5>File Based Store</h5>

  <p>The <em>File Based Store</em> implementation saves swapped out
  sessions in individual files (named based on the session identifier)
  in a configurable directory.  Therefore, you are likely to encounter
  scalability problems as the number of active sessions increases, and
  this should primarily be considered a means to easily experiment.</p>

  <p>To configure this, add a <code>&lt;Store&gt;</code> nested inside
  your <code>&lt;Manager&gt;</code> element with the following attributes:
  </p>

  <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><code>checkInterval</code></td><td valign="center" align="left">
      <p>The interval (in seconds) between checks for expired sessions
      among those sessions that are currently swapped out.  By default,
      this interval is set to 60 seconds (one minute).</p>
    </td></tr><tr><td valign="center" align="left"><strong><code>className</code></strong></td><td valign="center" align="left">
      <p>Java class name of the implementation to use.  This class must
      implement the <code>org.apache.catalina.Store</code> interface.  You
      <strong>must</strong> specify
      <code>org.apache.catalina.session.FileStore</code>
      to use this implementation.</p>
    </td></tr><tr><td valign="center" align="left"><code>directory</code></td><td valign="center" align="left">
      <p>Absolute or relative (to the temporary work directory for this web
      application) pathname of the directory into which individual session
      files are written.  If not specified, the temporary work directory
      assigned by the container is utilized.</p>
    </td></tr></table>


  <h5>JDBC Based Store</h5>

  <p>The <em>JDBC Based Store</em> implementation saves swapped out
  sessions in individual rows of a preconfigured table in a database
  that is accessed via a JDBC driver.  With large numbers of swapped out
  sessions, this implementation will exhibit improved performance over
  the File Based Store described above.</p>

  <p>To configure this, add a <code>&lt;Store&gt;</code> nested inside
  your <code>&lt;Manager&gt;</code> element with the following attributes:
  </p>

  <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><code>checkInterval</code></td><td valign="center" align="left">
      <p>The interval (in seconds) between checks for expired sessions
      among those sessions that are currently swapped out.  By default,
      this interval is set to 60 seconds (one minute).</p>
    </td></tr><tr><td valign="center" align="left"><strong><code>className</code></strong></td><td valign="center" align="left">
      <p>Java class name of the implementation to use.  This class must
      implement the <code>org.apache.catalina.Store</code> interface.  You
      <strong>must</strong> specify
      <code>org.apache.catalina.session.JDBCStore</code>
      to use this implementation.</p>
    </td></tr><tr><td valign="center" align="left"><strong><code>connectionURL</code></strong></td><td valign="center" align="left">
      <p>The connection URL that will be handed to the configured JDBC
      driver to establish a connection to the database containing our
      session table.</p>
    </td></tr><tr><td valign="center" align="left"><strong><code>driverName</code></strong></td><td valign="center" align="left">
      <p>Java class name of the JDBC driver to be used.</p>
    </td></tr><tr><td valign="center" align="left"><strong><code>sessionAppCol</code></strong></td><td valign="center" align="left">
      <p>Name of the database column, contained in the specified session
      table, that contains the Engine, Host, and Web Application Context
      name in the format <code>/Engine/Host/Context</code>.</p>
    </td></tr><tr><td valign="center" align="left"><strong><code>sessionDataCol</code></strong></td><td valign="center" align="left">
      <p>Name of the database column, contained in the specified
      session table, that contains the serialized form of all session
      attributes for a swapped out session.  The column type must accept
      a binary object (typically called a BLOB).</p>
    </td></tr><tr><td valign="center" align="left"><strong><code>sessionIdCol</code></strong></td><td valign="center" align="left">
      <p>Name of the database column, contained in the specified
      session table, that contains the session identifier of the
      swapped out session.  The column type must accept character
      string data of at least as many characters as are contained
      in session identifiers created by Tomcat (typically 32).</p>
    </td></tr><tr><td valign="center" align="left"><strong><code>sessionLastAccessedCol</code></strong></td><td valign="center" align="left">
      <p>Name of the database column, contained in the specified
      session table, that contains the <code>lastAccessedTime</code>
      property of this session.  The column type must accept a
      Java <code>long</code> (64 bits).</p>
    </td></tr><tr><td valign="center" align="left"><strong><code>sessionMaxInactiveCol</code></strong></td><td valign="center" align="left">
      <p>Name of the database column, contained in the specified
      session table, that contains the <code>maxInactiveInterval</code>
      property of this session.  The column type must accept a
      Java <code>integer</code> (32 bits).</p>
    </td></tr><tr><td valign="center" align="left"><strong><code>sessionTable</code></strong></td><td valign="center" align="left">
      <p>Name of the database table to be used for storing swapped out
      sessions.  This table must contain (at least) the database columns
      that are configured by the other attributes of this element.</p>
    </td></tr><tr><td valign="center" align="left"><strong><code>sessionValidCol</code></strong></td><td valign="center" align="left">
      <p>Name of the database column, contained in the specified
      session table, that contains a flag indicating whether this
      swapped out session is still valid or not.  The column type
      must accept a single character.</p>
    </td></tr></table>

  <p>Before attempting to use the JDBC Based Store for the first time,
  you must create the table that will be used to store swapped out sessions.
  Detailed SQL commands vary depending on the database you are using, but
  a script like this will generally be required:</p>

<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="../../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="../../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="../../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="../../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
create table tomcat_sessions (
  session_id     varchar(100) not null primary key,
  valid_session  char(1) not null,
  max_inactive   int not null,
  last_access    bigint not null,
  app_name       varchar(255),
  session_data   mediumblob,
  KEY kapp_name(app_name)
);
</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="../../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="../../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="../../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="../../images/void.gif"></td></tr></table></div>

  <p>In order for the JDBC Based Store to successfully connect to your
  database, the JDBC driver you configure must be visible to Tomcat's
  internal class loader.  Generally, that means you must place the JAR
  file containing this driver into the <code>$CATALINA_HOME/server/lib</code>
  directory (if your applications do not also need it) or into the
  <code>$CATALINA_HOME/common/lib</code> directory (if you wish to share
  this driver with your web applications.</p>

</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Special Features"><!--()--></a><a name="Special_Features"><strong>Special Features</strong></a></font></td></tr><tr><td><blockquote>


  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Restart Persistence"><!--()--></a><a name="Restart_Persistence"><strong>Restart Persistence</strong></a></font></td></tr><tr><td><blockquote>

    <p>Whenever Catalina is shut down normally and restarted, or when an
    application reload is triggered, the standard Manager implementation
    will attempt to serialize all currently active sessions to a disk
    file located via the <code>pathname</code> attribute.  All such saved
    sessions will then be deserialized and activated (assuming they have
    not expired in the mean time) when the application reload is completed.</p>

    <p>In order to successfully restore the state of session attributes,
    all such attributes MUST implement the <code>java.io.Serializable</code>
    interface.  You MAY cause the Manager to enforce this restriction by
    including the <code>&lt;distributable&gt;</code> element in your web
    application deployment descriptor (<code>/WEB-INF/web.xml</code>).</p>

  </blockquote></td></tr></table>

</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade="noshade"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em>
        Copyright &copy; 1999-2011, Apache Software Foundation
        </em></font></div></td></tr></table></body></html>